​Overview

This blog post will explain how conferences work in CIC by demonstrating conferencing using an IceLib example application. The example application is only intended to demonstrate the events related to conferencing, not necessarily how to build a custom client that supports conferencing. The application used in this example is published under the Mozilla open source license and is published on GitHub at https://github.com/InteractiveIntelligence/ConferenceExample

Conference Event Summary

A conference will generate the following events, based on the given actions, in this order:

1. Action: Place call
2. Event: InteractionAdded (first call)
3. Action: Place call
4. Event: InteractionAdded (second call)
5. Action: initiate conference
6. Event: InteractionAdded (user's call leg)
7. Event: InteractionRemoved (first call)
8. Event: InteractionRemoved (first call)
9. Event: ConferenceItemAdded (first call)
10. Event: InteractionRemoved (second call)
11. Event: InteractionRemoved (second call)
12. Event: ConferenceItemAdded (second call)
13. Action: Disconnect (first call)
14. Event: ConferenceItemChanged (first call)
15. Action: Disconnect (second call)
16. Event: ConferenceItemChanged (second call)
17. Event: InteractionChanged (user's call)
18. Event: ConferenceItemRemoved (first call)
19. Event: ConferenceItemRemoved (second call)
20. Event: InteractionRemoved (user's call - deallocation)

Example Application

The example application demonstrates conferencing by providing the ability to log in to CIC, place outbound calls, and conference them together. Referring to the first screenshot below, the application has the following features:

1. CIC Authentication - Use a CIC username, CIC password, workstation name, and CIC server name
2. Dial Controls - Enter a dialstring in the textbox and click the dial button to the right (handset icon)
3. Queue Window - This area displays the interactions on the logged in user's queue (My Interactions)
4. Call Controls - Click these buttons to act on the selected interaction
5. Output logging - Application messages will be written here. These messages will also be traced to the ININ tracelog for the application.

Conference Walkthrough

This section will show the application at each step in the conference process and will explain the IceLib events.

First call

This screenshot shows the fist call has been placed. The state is connected and the call can be used in a conference (noted by the appearance of the checkbox in the Conference column. Placing a new call will trigger one InteractionAdded event followed by several InteractionChanged events. The changed events are primarily for state changes as the call moves from initializing through the various stages to get to connected.

Second call

This screenshot shows the first and second calls both in queue. Both are available to be added to a conference. The second call generates the same events as the first, but with the new interaction id of the second call.

Pre-conferencing

This screenshot shows both interactions have been selected (checkboxes) to be added to a conference. Because multiple interactions are selected in this way, the call control buttons have been disabled and the Conference button has been enabled because two or more parties have been selected for a conference. Note that the UI updates are all reacting to logic built around various IceLib properties indicating the state and capabilities of the interactions.

Conference created

After clicking the conference button, the selected interactions are placed into conference. The application shows a collapsible record in the queue, which when expanded will show the current conference parties. The checkboxes have been hidden because the interactions are no longer eligible to be added to a conference because they are already in one.

The majority of confusion surrounding conferencing comes from the events directly following the creation of the conference. Consider these traces (changed traces removed for brevity and not important here):

11:49:35_9429218 - [Conference_Executed] -> Making a conference with interactions: 1001465853, 1001465856
11:49:36_0983593 - [QueueOnQueueContentsChanged] -> [1001465859] Interaction Added
11:49:36_1389631 - [QueueOnQueueContentsChanged] -> [1001465853] Interaction Removed
11:49:36_1587596 - [QueueOnQueueContentsChanged] -> [1001465853] Interaction Removed (was not in list)
11:49:36_1627199 - [QueueOnQueueContentsChanged] -> Conference item added: ConferenceId=1001465858, ConferenceItem=1001465853, Interaction=1001465859
11:49:36_1953944 - [QueueOnQueueContentsChanged] -> [1001465856] Interaction Removed
11:49:36_2023278 - [QueueOnQueueContentsChanged] -> [1001465856] Interaction Removed (was not in list)
11:49:36_2072747 - [QueueOnQueueContentsChanged] -> Conference item added: ConferenceId=1001465858, ConferenceItem=1001465856, Interaction=1001465859

The conference is created at the first trace message. The very first thing that happens is that a brand new interaction is added to the user's queue. In the example, this is 1001465859. This new interaction represents the connection of the user (call from station to CIC) and Interaction.IsOnMyInteractionsQueue will be true only for this interaction in the conference.

The next thing that happens in the conference process is that the first interaction provided when creating the conference, 1001465853 in this example, is removed from the user's queue. The removed event is recieved twice (the second one can be ignored). The interaction is then added to the conference. This same sequence of events (two removed, one conference added) happens for each of the remaining items that are to be conferenced.

In any of the conference events (added/changed/removed), the ConferenceId property is the ID for the conference object itself, ConferenceItem is the Interaction to which the event is referring, and Interaction is the Interaction object for "you" in the conference (the Interaction that is on the user's queue.

One interaction disconnected

One of the interactions in the conference has been disconnected and shows with grey text. This raises the conference item changed event for the interaction because its state has changed.

Conference ended

The other interaction in the conference is disconnected and the conference ends. The state description describes the state as Disconnected [Last conference party]. There are two key activities in this stage. First, the "other" interaction in the conference (that is not "you") is disconnected. This triggers the conference item changed event because the conference party has disconnected. CIC then determines that there is only one party remaining in the conference, which is the user's interaction, and disconnects that interaction also. This raises the interaction changed event for the user's interaction because the state changed.

The second action is that because all parties have been disconnected, CIC ends the conference. This triggers the conference item removed event for each party in the conference that is not the user's interaction (because the user's interaction is on the user's queue, and from the user's perspective, is not seen as a conference party).

Conference removed

The user's interaction is deallocated two minutes after the conference has ended and is removed from queue. This raises the interaction removed event, not the conference interaction removed event, because it is removing the user's interaction from their own queue. The conference interaction itself is never on the user's queue (it is on the CIC server or media server) and will therefore not generate a conference event for the user.

Notes About Conferencing

These are some things to consider when dealing with conferencing:

• There is no exact way to tell that an InteractionRemoved event will be followed by the interaction being added to a conference; the process is asynchronous and therefore the user application must respond based only on the events it receives and cannot predict which events it might receive.
• The point above becomes critical when dealing with DialerCallInteraction objects provided by the Dialer IceLib API. The ScreenPop event from the Dialer API will provide a DialerCallInteraction object, but there is currently no way to retrieve that object if the application loses its reference to it. All of the subsequent IceLib events will treat that interaction as a CallInteraction and not a Dialer object. Because of this, a Dialer IceLib application must be careful not to release the reference to the DialerCallInteraction object immediately on InteractionRemoved because it could be in the process of being added to a conference. The ConferenceItemAdded event will only provide a CallInteraction object, not a DialerCallInteraction object. The application should keep the reference for a couple seconds to see if the interaction gets added as a conference item in that timeframe. The Interaction ID of the Interaction in the ConferenceItemAdded event can be compared to the DialerCallInteraction's Interaction ID to determine if they are the same call. If they are, the application should retain the DialerCallInteraction object and discard the CallInteraction; subsequent changed and removed events will also have to compare the Interaction ID of the event to the Interaction ID of the Dialer object to determine equality.
• Conferencing events for chats function in the same way.
• To determine if an interaction can be put into a conference, check the interaction's capabilities. This is illustrated on line 105 in InteractionViewModel.cs with the code

  var conferenceCapabilitiy = (_interaction.Capabilities & InteractionCapabilities.Conference) > 0

  . This is doing a a bitwise operation on the property Interaction.Capabilities to determine if the value specifies that the interaction may be placed into conference. More reading about Capabilities can be found in the IceLib API documentation for InteractionCapabilities.
• Determining which interactions are part of the same conference can be determined by the conference ID of the interaction (Interaction.ConferenceId.Id). Interactions with the same conference ID are part of the same conference.
• IceLib provides six individual events for interactions and conferences from the InteractionQueue object (Interaction/Conference x Added/Changed/Removed). InteractionQueue also exposes a singular event, QueueContentsChanged, that provides the contents of all six of those events. An IceLib application should choose to use either some combination of the six events or the singular event; an application must not use any of the six individual events if the singular event is used. The example application in this blog uses the singular event for simplicity of coding. It should be noted that neither option is more correct or superior to the other for all situations. The purpose and design of the application will dictate if the singular event or a combination of the six individual events should be used.